Implementing active preview

Active preview is a new feature of VirtualDub 1.2 that allows the user to dynamically view the results of a filter's configuration settings in real-time.  The feature is handled through a new interface, IFilterPreview, that does most of the work for you.

How the active preview interface works

The IFilterPreview interface is available through the fa->ifp member. To make use of this interface, your filter must do the following:

VirtualDub stores the button handle when InitButton(HWND) is called, and will automatically change the label on a Toggle(HWND) or when the preview window is closed, so your filter need not worry about maintaining the label.  In addition, VirtualDub also automatically handles updating the preview display whenever the user uses the position buttons or slider.

When the preview is activated, VirtualDub initializes the current filter chain, thus calling your startProc, paramProc, and runProc routines, same as during a dub operation.  Similarly, the endProc method is invoked when the window closes.  Thus your filter must be reentrant enough to allow the processing portion to execute while the configuration dialog is displayed.  You can force VirtualDub to deinitialize and reinitialize the filter chain by using the UndoSystem() and RedoSystem() methods.  When a parameter is changed, you can redo any lookup tables and buffers the startProc routine may have created by calling UndoSystem(), changing the parameter in your private data structure, and then reinitializing the chain with RedoSystem().  VirtualDub will resize the preview window automatically if the size of the output frame changes due to new filter parameters.

If the user makes a trivial change that doesn't require redoing any tables or buffers and doesn't change any intermediate frames between the filters, you can simply call RedoFrame() to reprocess and redisplay the current frame.

The button callback

By installing a button callback, you can modify other parts of your dialog as the user opens and closes the active preview window:

void IFilterPreview::SetButtonCallback(FilterPreviewButtonCallback, void *);

void *FilterPreviewButtonCallback(bool fNewState, void *pData);

When you install the button callback, VirtualDub calls your callback function every time the active preview opens or closes.  For instance, you can replace the IFilterPreview::InitButton() functionality using this callback.  The button callback is most useful for dimming sampling buttons used for sampling incoming video.

Subtleties of active preview

The old method of filling in your data structure on a WM_COMMAND: IDOK message won't work anymore, because filter parameters in the data structure have to be changed on the fly.  One way around this problem is to make a temporary copy of your data structure, and then use that to restore the original data if the user selects Cancel.

Another problem is illegal values, such as resizing to -1x-1.  You can trap these in the dialog, by beeping and not accepting bad values, or by substituting valid values when needed.  Alternatively, you can trap them in startProc.  Edit fields are a special problem because partial values arrive as the user types in the numbers; in this case, it is recommended that you examine and act only when the user leaves the edit field, i.e. the EN_KILLFOCUS notification message.  In addition to avoiding partial number problems, this also avoids annoying lags when working with complex filter chains that take a third of a second or more per frame.

[up] back to main page


VirtualDub external filter SDK 1.05©1999-2001 Avery Lee <phaeron@virtualdub.org>